---
title: 구성 참조
i18nReady: true
githubURL: https://github.com/withastro/astro/blob/main/packages/astro/src/types/public/config.ts
---

import Since from '~/components/Since.astro';

다음 참조는 Astro에서 지원되는 모든 구성 옵션을 다룹니다.

```js
// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  // 구성 옵션은 여기에 작성합니다...
});
```

## 최상위 옵션

### site

<p>

**타입:** `string`

</p>

배포된 최종 URL입니다. Astro는 이 전체 URL을 사용하여 최종 빌드에서 사이트맵과 표준 URL을 생성합니다. Astro를 최대한 활용하려면 이 구성을 설정하는 것이 좋습니다.

```js
{
  site: 'https://www.my-site.dev';
}
```

### base

<p>

**타입:** `string`

</p>

배포할 기본 경로입니다. Astro는 개발 및 프로덕션 빌드 모두에서 이 경로를 페이지 및 자산의 루트로 사용합니다.

아래 예에서 `astro dev`는 `/docs`에서 서버를 시작합니다.

```js
{
  base: '/docs';
}
```

이 옵션을 사용할 때 모든 정적 자산 가져오기 및 URL은 base를 접두사로 추가해야 합니다. `import.meta.env.BASE_URL`을 통해 이 값에 액세스할 수 있습니다.

`import.meta.env.BASE_URL`의 값은 `base`에 어떤 값을 설정했는지에 관계없이 `trailingSlash` 구성에 의해 결정됩니다.

`trailingSlash: "always"`가 설정된 경우 후행 슬래시가 항상 포함됩니다. `trailingSlash: "never"`가 설정된 경우 `base`에 슬래시가 포함되어 있더라도 `BASE_URL`에는 후행 슬래시가 포함되지 않습니다.

또한 Astro는 통합에 사용할 수 있도록 하기 전에 `config.base`의 구성된 값을 내부적으로 조작합니다. 통합에서 읽은 `config.base` 값도 동일한 방식으로 `trailingSlash` 구성에 따라 결정됩니다.

아래 예시에서, `import.meta.env.BASE_URL` 및 `config.base` 값은 모두 `/docs`가 됩니다.

```js
{
	 base: '/docs/',
	 trailingSlash: "never"
}
```

아래 예시에서 `import.meta.env.BASE_URL` 및 `config.base` 값은 모두 `/docs/`가 됩니다.

```js
{
	 base: '/docs',
	 trailingSlash: "always"
}
```

### trailingSlash

<p>

**타입:** `'always' | 'never' | 'ignore'`<br />
**기본값:** `'ignore'`

</p>

개발 서버 및 요청 시 렌더링되는 페이지에서 후행 슬래시에 대한 경로 일치 동작을 설정합니다. 다음 옵션 중에서 선택합니다:
  - `'ignore'` - 후행 "/"의 존재 여부에 관계없이 URL을 일치시킵니다. "/about" 및 "/about/"에 대한 요청은 모두 동일한 경로와 일치합니다.
  - `'always'` - 후행 슬래시 (예: "/about/")가 포함된 URL만 일치시킵니다. 프로덕션 환경에서는 사용자의 편의를 위해, 요청 시 렌더링되는 후행 슬래시가 없는 URL에 대한 요청이 올바른 URL로 리디렉션됩니다. 그러나 개발 환경에서는 `always`가 구성되었음을 알리는 경고 페이지가 표시됩니다.
  - `'never'` - 후행 슬래시 (예: "/about")가 포함되지 않은 URL만 일치시킵니다. 프로덕션 환경에서는 사용자의 편의를 위해, 요청 시 렌더링되는 후행 슬래시가 포함된 URL에 대한 요청이 올바른 URL로 리디렉션됩니다. 그러나 개발 환경에서는 `never`가 구성되었음을 알리는 경고 페이지가 표시됩니다.

프로덕션 환경에서 GET 요청에 대한 리디렉션이 발생하면 리디렉션은 301(영구) 리디렉션이 됩니다. 다른 모든 요청 메서드의 경우 308(영구, 요청 메서드 보존) 리디렉션이 됩니다.

미리 렌더링된 페이지의 후행 슬래시는 호스팅 플랫폼에서 처리되며 선택한 구성을 따르지 않을 수 있습니다.
자세한 내용은 호스팅 플랫폼의 문서를 참조하세요. 현재 이 사용 사례에서는 Astro [리디렉션](#redirects)을 사용할 수 없습니다.


```js
{
  // 예: 개발 중에 후행 슬래시가 필요합니다.
  trailingSlash: 'always';
}
```

**참고하기:**

- build.format

### redirects

<p>

**타입:** `Record<string, RedirectConfig>`<br />
**기본값:** `{}`<br />

<Since v="2.9.0" />
</p>

키는 일치시킬 경로이고 값은 리디렉션할 경로인 리디렉션 매핑을 지정합니다.

정적 경로와 동적 경로를 모두 리디렉션할 수 있지만 동일한 종류의 경로로만 리디렉션할 수 있습니다.
예를 들어, `'/article': '/blog/[...slug]'` 리디렉션을 사용할 수 없습니다.

```js
export default defineConfig({
  redirects: {
    '/old': '/new',
    '/blog/[...slug]': '/articles/[...slug]',
    '/about': 'https://example.com/about',
    '/news': {
      status: 302,
      destination: 'https://example.com/news'
    },
   // '/product1/', '/product1' // 참고: 현재 지원되지 않음
	}
})
```

어댑터가 설치되지 않은 정적으로 생성된 사이트의 경우 [`<meta http-equiv="refresh">` 태그](https://developer.mozilla.org/ko/docs/Web/HTML/Element/meta#http-equiv)를 사용하여 클라이언트 리디렉션을 생성하며 상태 코드는 지원하지 않습니다.

`output: static` 모드에서 SSR을 사용하거나 정적 어댑터를 사용하는 경우 상태 코드가 지원됩니다.
Astro는 `301` 상태로 리디렉션된 GET 요청을 처리하고 다른 요청 방법에는 `308` 상태를 사용합니다.

리디렉션 구성의 객체를 사용하여 [리디렉션 상태 코드](https://developer.mozilla.org/ko/docs/Web/HTTP/Status#%EB%A6%AC%EB%8B%A4%EC%9D%B4%EB%A0%89%EC%85%98_%EB%A9%94%EC%8B%9C%EC%A7%80)를 맞춤설정할 수 있습니다.

```js
export default defineConfig({
  redirects: {
    '/other': {
      status: 302,
      destination: '/place',
    },
  }
})


```

### output

<p>

**타입:** `'static' | 'server'`<br />
**기본값:** `'static'`

</p>

빌드의 출력 대상을 지정합니다.

- `'static'` - 기본적으로 모든 페이지를 사전 렌더링하여, 어떤 페이지도 사전 렌더링을 거부하지 않는 경우 완전히 정적인 사이트를 출력합니다.
- `'server'` - 기본적으로 모든 페이지에 서버 측 렌더링(SSR)을 사용하여, 항상 서버에서 렌더링된 사이트를 출력합니다.

```js
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static',
});
```

**참고하기:**

- adapter

### adapter

<p>

**타입:** `AstroIntegration`

</p>

빌드 어댑터를 사용하여 선호하는 서버, 서버리스, 엣지 호스트에 배포합니다. Astro에서 제공하는 기본 어댑터([Cloudflare](/ko/guides/integrations-guide/cloudflare/), [Netlify](/ko/guides/integrations-guide/netlify/), [Node.js](/ko/guides/integrations-guide/node/), [Vercel](/ko/guides/integrations-guide/vercel/)) 중 하나를 가져오거나, [커뮤니티 어댑터](https://astro.build/integrations/2/?search=&categories%5B%5D=adapters)를 탐색하여 Astro 프로젝트의 요청 시 렌더링을 활성화하세요.

Astro의 서버 렌더링 옵션에 대한 자세한 내용은 [요청 시 렌더링 가이드](/ko/guides/on-demand-rendering/)를 참조하세요.

```js
import netlify from '@astrojs/netlify';
{
  // 예: Netlify 서버리스 배포를 위한 빌드
  adapter: netlify(),
}
```

**참고하기:**

- output

### integrations

맞춤형 통합으로 Astro를 확장하세요. 통합은 프레임워크 지원 (Solid.js 등), 새로운 기능 (사이트맵 등), 새 라이브러리(Partytown 등)를 한번에 추가하는 것을 도와줍니다.

Astro 통합을 시작하는 데 도움이 필요하면 [통합 가이드](/ko/guides/integrations-guide/)를 읽어보세요.

```js
import react from '@astrojs/react';
import mdx from '@astrojs/mdx';
{
  // 예: Astro에 React + MDX 지원 추가
  integrations: [react(), mdx()];
}
```

### root

<p>

**타입:** `string`<br />
**CLI:** `--root`<br />
**기본값:** `"."` (현재 작업 디렉터리)

</p>

프로젝트 루트 디렉터리가 아닌 디렉터리에서 `astro` CLI 명령을 실행하는 경우에만 이 옵션을 제공해야 합니다. 일반적으로 이 옵션은 Astro 구성 파일 대신 CLI를 통해 제공됩니다. Astro가 구성 파일을 찾으려면 먼저 프로젝트 루트를 알아야 하기 때문입니다.

상대 경로를 제공하는 경우 (예: `--root: './my-project'`) Astro는 현재 작업 디렉터리를 기준으로 경로를 확인합니다.

#### 예

```js
{
  root: './my-project-directory';
}
```

```bash
$ astro build --root ./my-project-directory
```

### srcDir

<p>

**타입:** `string`<br />
**기본값:** `"./src"`

</p>

Astro가 여러분의 사이트를 읽을 디렉터리를 설정하세요.

값은 절대 파일 시스템 경로이거나 프로젝트 루트에 대한 상대 경로일 수 있습니다.

```js
{
  srcDir: './www';
}
```

### publicDir

<p>

**타입:** `string`<br />
**기본값:** `"./public"`

</p>

정적 자산의 디렉터리를 설정합니다. 이 디렉터리의 파일은 개발 중에 `/`에 제공되고 빌드 중에 build 디렉터리에 복사됩니다. 이러한 파일은 변환이나 번들링 없이 항상 있는 그대로 제공되거나 복사됩니다.

값은 절대 파일 시스템 경로이거나 프로젝트 루트에 대한 상대 경로일 수 있습니다.

```js
{
  publicDir: './my-custom-publicDir-directory';
}
```

### outDir

<p>

**타입:** `string`<br />
**기본값:** `"./dist"`

</p>

`astro build`가 최종 빌드를 작성하는 디렉터리를 설정합니다.

값은 절대 파일 시스템 경로이거나 프로젝트 루트에 대한 상대 경로일 수 있습니다.

```js
{
  outDir: './my-custom-build-directory';
}
```

**참고하기:**

- build.server

### cacheDir

<p>

**타입:** `string`<br />
**기본값:** `"./node_modules/.astro"`

</p>

빌드 아티팩트를 캐싱하기 위한 디렉터리를 설정합니다. 이 디렉터리의 파일은 빌드 시간을 단축하기 위해 후속 빌드에서 사용됩니다.

값은 절대 파일 시스템 경로이거나 프로젝트 루트에 대한 상대 경로일 수 있습니다.

```js
{
  cacheDir: './my-custom-cache-directory';
}
```

### compressHTML

<p>

**타입:** `boolean`<br />
**기본값:** `true`

</p>

이는 HTML 출력을 최소화하고 HTML 파일의 크기를 줄이는 옵션입니다.

기본적으로 Astro는 `.astro` 컴포넌트에서 줄 바꿈을 포함하여 HTML의 공백을 무손실 방식으로 제거합니다.
HTML의 시각적 렌더링을 유지하기 위해 필요에 따라 일부 공백이 유지될 수 있습니다. 이는 개발 모드와 최종 빌드 모두에서 발생합니다.

HTML 압축을 비활성화하려면 `compressHTML`을 false로 설정하세요.

```js
{
  compressHTML: false;
}
```

### scopedStyleStrategy

<p>

**타입:** `'where' | 'class' | 'attribute'`<br />
**기본값:** `'attribute'`<br />

<Since v="2.4" />
</p>

Astro 컴포넌트에서 스타일 범위 지정에 사용되는 전략을 지정합니다. 다음 중에서 선택하세요:

- `'where'` - `:where` 선택자를 사용하면 구체성이 증가하지 않습니다.
- `'class'` - 클래스 기반 선택기를 사용하면 구체성이 +1 증가합니다.
- `'attribute'` - `data-` 속성을 사용하면 구체성이 +1 증가합니다.

Astro 컴포넌트의 요소 선택기가 전역 스타일 기본값 (예: 전역 스타일시트)을 재정의하도록 하려는 경우 `'class'`를 사용하는 것이 도움이 됩니다.
``where'`를 사용하면 구체성을 더 잘 제어할 수 있지만, 적용되는 선택기를 제어하려면 더 높은 구체성 선택기, 레이어 및 기타 도구를 사용해야 합니다.
`'attribute'`를 사용하는 것은 요소의 `class` 속성을 조작하고 자신의 스타일 지정 로직과 Astro의 스타일 적용 사이의 충돌을 피해야 할 때 유용합니다.

### security

<p>

**타입:** `Record<"checkOrigin", boolean> | undefined`<br />
**기본값:** `{checkOrigin: true}`<br />
<Since v="4.9.0" />
</p>

Astro 웹사이트에 대한 보안 조치를 활성화합니다.

이러한 기능은 `server` 모드를 사용하여 요청 시 렌더링된 페이지 (SSR) 또는 `static` 모드에서 사전 렌더링을 선택 해제한 페이지에만 존재합니다.

기본적으로 Astro는 요청 시 렌더링된 페이지의 각 요청에서 전송된 URL과 "origin" 헤더가 일치하는지 확인합니다. `checkOrigin`을 `false`로 설정하여 이 동작을 비활성화할 수 있습니다:

```js
// astro.config.mjs
export default defineConfig({
  output: "server",
  security: {
    checkOrigin: false
  }
})
```

#### security.checkOrigin

<p>

**타입:** `boolean`<br />
**기본값:** `true`<br />
<Since v="4.9.0" />
</p>

모든 최신 브라우저에서 자동으로 전달되는 "origin" 헤더가 각 `Request`에서 보낸 URL과 일치하는지 확인합니다. 이는 CSRF (Cross-Site Request Forgery) 보호를 위해 사용됩니다.

"origin" 확인은 요청 시 렌더링된 페이지에 대해서만 실행되며, `content-type` 헤더가 `'application/x-www-form-urlencoded'`, `'multipart/form-data'`, `'text/plain'` 중 하나인 `POST`, `PATCH`, `DELETE`, `PUT` 요청에 대해서만 실행됩니다.

"origin" 헤더가 요청의 `pathname`과 일치하지 않으면 Astro는 403 상태 코드를 반환하며 페이지를 렌더링하지 않습니다.

#### security.allowedDomains

<p>

**타입:** `Array<RemotePattern>`<br />
**기본값:** `[]`<br />
<Since v="5.14.2" />
</p>

SSR 사용 시 들어오는 요청에 대해 허용되는 호스트 패턴 목록을 정의합니다. 설정 시 Astro는 보안을 위해 `X-Forwarded-Host` 헤더를 이 패턴들과 대조하여 검증합니다. 헤더가 허용된 패턴과 일치하지 않으면 해당 헤더는 무시되고 요청의 원래 호스트가 대신 사용됩니다.

이는 악의적인 행위자가 조작된 `X-Forwarded-Host` 헤더를 전송하여 `Astro.url` 값을 조작할 수 있는 호스트 헤더 주입 공격을 방지합니다.

각 패턴은 `protocol`, `hostname`, `port`를 지정할 수 있습니다. 제공된 옵션에 대해 유효성 검사를 수행합니다. 패턴은 유연한 호스트명 일치를 위해 와일드카드를 지원합니다.

```js
{
  security: {
    // 예시: example.com의 모든 하위 도메인에 대해 https를 허용합니다.
    allowedDomains: [
      {
        hostname: '**.example.com',
        protocol: 'https'
      },
      {
        hostname: 'staging.myapp.com',
        protocol: 'https',
        port: '443'
      }
    ]
  }
}
```

이 설정이 구성되지 않으면, `X-Forwarded-Host` 헤더는 신뢰되지 않으며 무시됩니다.

### vite

<p>

**타입:** `ViteUserConfig`

</p>

추가 구성 옵션을 Vite에 전달합니다. Astro가 필요할 수 있는 일부 고급 구성을 지원하지 않을 때 유용합니다.

[vite.dev](https://ko.vite.dev/config/)에서 전체 `vite` 구성 객체 문서를 확인하세요.

#### 예

```js
{
  vite: {
    ssr: {
      // 예: 필요한 경우, 손상된 패키지가 SSR 처리를 건너뛰도록 강제합니다.
      external: ['broken-npm-package'],
    }
  }
}
```

```js
{
  vite: {
    // 예: Astro 프로젝트에 직접 맞춤형 vite 플러그인 추가
    plugins: [myPlugin()],
  }
}
```

## 빌드 옵션

### build.format

<p>

**타입:** `('file' | 'directory' | 'preserve')`<br />
**기본값:** `'directory'`

</p>

각 페이지의 출력 파일 형식을 제어합니다. 이 값은 어댑터에 의해 설정될 수 있습니다.

- `'file'`: Astro는 각 페이지 경로에 대해 이름이 지정된 HTML 파일을 생성합니다. (예를 들어 `src/pages/about.astro`와 `src/pages/about/index.astro`는 모두 `/about.html` 파일을 빌드합니다)
- `'directory'`: Astro는 각 페이지에 대해 중첩된 `index.html` 파일이 있는 디렉터리를 생성합니다. (예를 들어 `src/pages/about.astro`와 `src/pages/about/index.astro`는 모두 `/about/index.html` 파일을 빌드합니다)
- `'preserve'`: Astro는 소스 폴더에 나타나는 HTML 파일을 정확하게 생성합니다. (예를 들어 `src/pages/about.astro`는 `/about.html`을 빌드하고 `src/pages/about/index.astro`는 `/about/index.html` 파일을 빌드합니다.)

```js
{
  build: {
    // 예: 빌드 중에 `page/index.html` 대신 `page.html`을 생성합니다.
    format: 'file';
  }
}
```

#### Astro.url에 미치는 영향

`build.format`을 설정하면 빌드 중에 `Astro.url`이 무엇으로 설정될지 제어할 수 있습니다.

- `directory` - `Astro.url.pathname`에는 폴더 동작을 모방하기 위해 후행 슬래시가 포함됩니다. 즉 `/foo/`입니다.
- `file` - `Astro.url.pathname`에는 `.html`이 포함됩니다. 즉 `/foo.html`입니다.

이는 `new URL('./relative', Astro.url)`을 사용하여 상대 URL을 생성할 때 개발과 빌드 간에 일관된 동작을 얻게 된다는 것을 의미합니다.

개발에서 후행 슬래시 동작의 불일치를 방지하려면 빌드 형식에 따라 [`trailingSlash` 옵션](#trailingslash)을 `'always'` 또는 `'never'`로 제한할 수 있습니다.

- `directory` - `trailingSlash: 'always'`로 설정됩니다.
- `file` - `trailingSlash: 'never'`로 설정됩니다.

### build.client

<p>

**타입:** `string`<br />
**기본값:** `'./client'`
</p>

서버 렌더링 된 페이지로 사이트를 구축하는 경우, 클라이언트측 CSS 및 JavaScript의 출력 디렉터리를 제어합니다.
`outDir`은 코드가 빌드되는 위치를 제어합니다.

이 값은 `outDir`을 기준으로 합니다.

```js
{
  output: 'server',
  build: {
    client: './client'
  }
}
```

### build.server

<p>

**타입:** `string`<br />
**기본값:** `'./server'`
</p>

SSR로 빌드할 때 서버 JavaScript의 출력 디렉터리를 제어합니다.

이 값은 `outDir`을 기준으로 합니다.

```js
{
  build: {
    server: './server';
  }
}
```

### build.assets

<p>

**타입:** `string`<br />
**기본값:** `'_astro'`<br />

<Since v="2.0.0" />
</p>

Astro에서 생성된 자산 (예: JS 및 CSS 번들)이 있어야 하는 빌드 출력의 디렉터리를 지정합니다.

```js
{
  build: {
    assets: '_custom';
  }
}
```

**참고하기:**

- outDir

### build.assetsPrefix

<p>

**타입:** `string | Record<string, string>`<br />
**기본값:** `undefined`<br />

<Since v="2.2.0" />
</p>

Astro에서 생성된 자산 링크의 접두사를 지정합니다. 자산이 현재 사이트와 다른 도메인에서 제공되는 경우 사용할 수 있습니다.

이를 위해서는 로컬 `./dist/_astro` 폴더의 자산을 원격 도메인의 해당 `/_astro/` 폴더에 업로드해야 합니다.

`_astro` 경로의 이름을 바꾸려면 `build.assets`에 새 디렉터리를 지정합니다.

동일한 도메인 (예: `https://cdn.example.com/_astro/...`)에 업로드된 모든 자산을 가져오려면 `assetsPrefix`를 루트 도메인의 문자열로 설정합니다. (`base` 구성에 관계없이):

```js
{
  build: {
    assetsPrefix: 'https://cdn.example.com';
  }
}
```
**추가:** `astro@4.5.0`

또한 `assetsPrefix`에 객체를 전달하여 각 파일 형식에 대해 서로 다른 도메인을 지정할 수도 있습니다.
이 경우 `fallback` 속성이 필요하며 기본적으로 다른 파일에 사용됩니다.

```js
{
  build: {
    assetsPrefix: {
      'js': 'https://js.cdn.example.com',
      'mjs': 'https://js.cdn.example.com',
      'css': 'https://css.cdn.example.com',
      'fallback': 'https://cdn.example.com'
    }
  }
}
```

### build.serverEntry

<p>

**타입:** `string`<br />
**기본값:** `'entry.mjs'`

</p>

SSR로 빌드할 때 서버 엔트리포인트의 파일 이름을 지정합니다.
이 엔트리포인트는 일반적으로 배포하려는 호스트에 따라 달라지며 어댑터에 의해 설정됩니다.

런타임에서 파일이 JavaScript 모듈임을 감지할 수 있도록 이 파일은 `.mjs`로 끝나는 것이 좋습니다.

```js
{
  build: {
    serverEntry: 'main.mjs';
  }
}
```

### build.redirects

<p>

**타입:** `boolean`<br />
**기본값:** `true`<br />

<Since v="2.6.0" />
</p>

빌드 중에 리디렉션을 HTML로 출력할지 여부를 지정합니다.
이 옵션은 `output: 'static'` 모드에만 적용됩니다. SSR 리디렉션에서는 모든 응답과 동일하게 처리됩니다.

이 옵션은 주로 리디렉션을 위한 특수 구성 파일이 있고 HTML 기반 리디렉션이 필요하지 않거나 필요하지 않은 어댑터에서 사용하기 위한 것입니다.

```js
{
  build: {
    redirects: false;
  }
}
```

### build.inlineStylesheets

<p>

**타입:** `'always' | 'auto' | 'never'`<br />
**기본값:** `auto`<br />

<Since v="2.6.0" />
</p>

프로젝트 스타일을 별도의 CSS 파일로 브라우저에 보낼지 `<style>` 태그에 인라인할지 제어합니다. 다음 옵션 중에서 선택하세요.

- `'always'` - 프로젝트 스타일은 `<style>` 태그에 인라인됩니다.
- `'auto'` - `ViteConfig.build.assetsInlineLimit` (기본값: 4kb)보다 작은 스타일시트만 인라인됩니다. 그렇지 않으면 프로젝트 스타일이 외부 스타일시트로 전송됩니다.
- `'never'` - 프로젝트 스타일은 외부 스타일시트로 전송됩니다.

```js
{
	build: {
		inlineStylesheets: `never`,
	},
}
```

### build.concurrency

<p>

**타입:** `number`<br />
**기본값:** `1`<br />
<Since v="4.16.0" />
</p>

병렬로 빌드할 페이지 수입니다.

**대부분의 경우 기본값인 `1`을 변경하지 않아야 합니다.**

이 옵션은 전체 렌더링 시간을 줄이기 위한 다른 시도 (예: 가져오기 호출 또는 데이터 액세스와 같은 장기 실행 작업의 배치 또는 캐시)가 불가능하거나 충분하지 않은 경우에만 사용하세요.
이 수치를 너무 높게 설정하면 메모리 리소스가 부족해지고 JS가 단일 스레드이기 때문에 페이지 렌더링 속도가 느려질 수 있습니다.

```js
{
  build: {
    concurrency: 2
  }
}
```

 :::caution[주요 변경 사항 발생 가능]
 이 기능은 안정적이며 실험적인 것으로 간주되지 않습니다. 그러나 이 기능은 어려운 성능 문제를 해결하기 위한 용도로만 사용되며, 이 옵션의 성능을 최대한 유지하기 위해 [마이너 릴리스](/ko/upgrade-astro/#의미론적-버전-관리)에서 주요 변경 사항이 발생할 수 있습니다. 이 기능을 사용하는 경우 모든 마이너 릴리스에 대한 [Astro 변경 로그](https://github.com/withastro/astro/blob/refs/heads/next/packages/astro/CHANGELOG.md)를 확인하시기 바랍니다.
 :::

## 서버 옵션

`astro dev`와 `astro preview` 모두에서 사용되는 Astro 개발 서버를 사용자 정의하세요.

```js
{
  server: { port: 1234, host: true}
}
```

실행 명령 ("dev", "preview")을 기반으로 다른 구성을 설정하려면 이 구성 옵션에 함수를 전달할 수도 있습니다.

```js
{
  // 예: 함수 구문을 사용하여 명령에 따라 사용자 정의
  server: ({ command }) => ({ port: command === 'dev' ? 4321 : 4000 });
}
```

### server.host

<p>

**타입:** `string | boolean`<br />
**기본값:** `false`<br />

<Since v="0.24.0" />
</p>

서버가 수신해야 하는 네트워크 IP 주소 (예: 로컬 호스트가 아닌 IP)를 설정합니다.

- `false` - 네트워크 IP 주소를 노출하지 않습니다.
- `true` - LAN 및 공용 주소를 포함한 모든 주소에서 수신합니다.
- `[custom-address]` - `[custom-address]` (예: `192.168.0.1`)의 네트워크 IP 주소를 노출합니다.

### server.port

<p>

**타입:** `number`<br />
**기본값:** `4321`

</p>

서버가 수신해야 하는 포트를 설정합니다.

주어진 포트가 이미 사용 중이라면 Astro는 자동으로 다음 사용 가능한 포트를 시도합니다.

```js
{
  server: {
    port: 8080;
  }
}
```

### server.allowedHosts

<p>

**타입:** `Array<string> | true`<br />
**기본값:** `[]`<br />
<Since v="5.4.0" />
</p>

Astro가 응답하도록 허용된 호스트 이름의 목록입니다. 값이 `true`로 설정되면 모든 호스트 이름이 허용됩니다.

```js
{
  server: {
  	allowedHosts: ['staging.example.com', 'qa.example.com']
  }
}
```

### server.open

<p>

**타입:** `string | boolean`<br />
**기본값:** `false`<br />

<Since v="2.1.8" />
</p>

시작 시 개발 서버가 브라우저 창에서 열릴지 여부를 제어합니다.

열려는 URL을 지정하려면 전체 URL 문자열 (예: "http://example.com") 또는 경로 이름 (예: "/about")을 전달하세요.

```js
{
  server: {
    open: '/about';
  }
}
```

### server.headers

<p>

**타입:** `OutgoingHttpHeaders`<br />
**기본값:** `{}`<br />

<Since v="1.7.0" />
</p>

`astro dev` 및 `astro preview`에서 전송되도록 사용자 정의 HTTP 응답 헤더를 설정합니다.

## 세션 옵션

<p>

<Since v="5.7.0" />
</p>

Astro 프로젝트의 세션 스토리지를 구성합니다. 이는 세션 데이터를 영구적인 방식으로 저장하여 여러 요청에 걸쳐 접근할 수 있도록 하는 데 사용됩니다.
일부 어댑터는 기본 세션 드라이버를 제공할 수 있지만, 사용자 정의 구성으로 이를 덮어쓸 수 있습니다.

더 자세한 내용은 [세션 가이드](/ko/guides/sessions/)를 참조하세요.

```js title="astro.config.mjs"
  {
    session: {
      // Unstorage 드라이버의 이름
      driver: 'redis',
      // 드라이버에 따른 필수 옵션
      options: {
        url: process.env.REDIS_URL,
      },
      ttl: 3600, // 1시간
    }
  }
```

### session.driver

<p>

**타입:** `string | undefined`<br />
<Since v="5.7.0" />
</p>

세션 스토리지를 위해 사용할 Unstorage 드라이버입니다. [Node](/ko/guides/integrations-guide/node/#세션), [Cloudflare](/ko/guides/integrations-guide/cloudflare/#세션), [Netlify](/ko/guides/integrations-guide/netlify/#세션) 어댑터는 자동으로 기본 드라이버를 구성하지만, 기본 드라이버를 제공하지 않는 어댑터를 선호하거나 사용하는 경우 사용자 정의 드라이버를 지정할 수 있습니다.

이 값은 [Unstorage 드라이버 문서](https://unstorage.unjs.io/drivers)에 있는 "드라이버 이름"입니다.

```js title="astro.config.mjs" ins={4}
{
  adapter: vercel(),
  session: {
    driver: "redis",
  },
}
```
:::note
일부 드라이버는 추가 패키지 설치가 필요할 수 있습니다. 또한 일부 드라이버는 환경 변수나 자격 증명 설정을 요구할 수도 있습니다. 자세한 내용은 [Unstorage 문서](https://unstorage.unjs.io/drivers)를 참조하세요.
:::

### session.options

<p>

**타입:** `Record<string, unknown> | undefined`<br />
**기본값:** `{}`<br />
<Since v="5.7.0" />
</p>

세션 스토리지를 위해 사용할 드라이버별 옵션입니다. 옵션은 사용 중인 드라이버에 따라 다릅니다. 각 드라이버에서 사용할 수 있는 옵션에 대한 자세한 내용은 [Unstorage 문서](https://unstorage.unjs.io/drivers)를 참조하세요.

```js title="astro.config.mjs" ins={4-6}
{
   session: {
     driver: "redis",
     options: {
       url: process.env.REDIS_URL
     },
   }
}
```

### session.cookie

<p>

**타입:** `string | AstroCookieSetOptions | undefined`<br />
**기본값:** `{ name: "astro-session", sameSite: "lax", httpOnly: true, secure: true }`<br />
<Since v="5.7.0" />
</p>

세션 쿠키 구성입니다. 문자열로 설정하면 쿠키 이름으로 사용됩니다. 또는 추가 옵션이 있는 객체를 전달할 수도 있습니다. 이 옵션들은 기본 설정과 병합됩니다.

```js title="astro.config.mjs" ins={3-4}
{
 session: {
   // 문자열로 설정하면 쿠키 이름으로 사용됩니다.
   cookie: "my-session-cookie",
 }
}

```

```js title="astro.config.mjs" ins={4-8}
{
 session: {
   // 객체로 설정하면 쿠키 옵션으로 사용됩니다.
   cookie: {
     name: "my-session-cookie",
     sameSite: "lax",
     secure: true,
   }
 }
}
```

### session.ttl

<p>

**타입:** `number | undefined`<br />
**기본값:** {Infinity}<br />
<Since v="5.7.0" />
</p>

세션 값에 대한 선택적 기본 만료 시간(초)입니다.

기본적으로 세션 값은 삭제되거나 세션이 파괴될 때까지 유지되며, 특정 시간이 경과해도 자동으로 만료되지 않습니다. 세션 값에 대한 기본 만료 기간을 추가하려면 `session.ttl`을 설정하세요. [`session.set()`](/ko/reference/api-reference/#set)에 `ttl` 옵션을 전달하면 해당 개별 항목에 대한 전역 기본값을 덮어씁니다.

```js title="astro.config.mjs" ins={3-4}
{
 session: {
   // 기본 만료 기간을 1시간 (3600초)으로 설정합니다.
   ttl: 3600,
 }
}
```
:::note
`ttl` 값을 설정해도 스토리지에서 해당 값이 시간 제한으로 인해 자동으로 삭제되지는 않습니다.

스토리지의 값은 `ttl` 기간이 만료된 후 접근하려는 시도가 있을 때만 삭제됩니다. 이때 세션 값은 undefined가 되고, 그 후에야 값이 삭제됩니다.

개별 드라이버는 지정된 시간 이후에 세션을 자동으로 삭제하는 `ttl` 옵션을 지원할 수도 있습니다. 자세한 내용은 선택한 드라이버의 문서를 참조하세요.
:::

## 개발 툴바 옵션

### devToolbar.enabled

<p>

**타입:** `boolean`<br />
**기본값:** `true`

</p>

Astro 개발 툴바를 활성화할지 여부입니다. 이 툴바를 사용하면 페이지 아일랜드를 검사하고 성능 및 접근성에 대한 유용한 정보를 볼 수 있습니다.

이 옵션은 전체 프로젝트로 범위가 지정되며, 자신에 대해서만 툴바를 비활성화하려면 `npm run astro preferences disable devToolbar`를 실행하세요. 모든 Astro 프로젝트에 대한 툴바를 비활성화하려면 `npm run astro preferences disable devToolbar --global`을 실행하세요.

## 프리페치 옵션

<p>

**타입:** `boolean | object`

</p>

더 빠른 페이지 전환을 제공하려면 사이트의 링크에 대해 프리페치를 활성화하세요.
(`<ClientRouter />` 라우터를 사용하는 페이지에서는 기본적으로 활성화됩니다. 이 동작을 선택하지 않으려면 `prefetch: false`를 설정하세요.)

이 구성은 프로젝트의 모든 페이지에 프리페치 스크립트를 자동으로 추가하여 `data-astro-prefetch` 속성에 대한 액세스를 제공합니다.
해당 페이지에 대한 프리페칭을 활성화하려면 페이지의 `<a />` 링크에 이 속성을 추가하세요.

```html
<a href="/about" data-astro-prefetch>About</a>
```

[`prefetch.defaultStrategy`](#prefetchdefaultstrategy) 및 [`prefetch.prefetchAll`](#prefetchprefetchall) 옵션을 사용하여 기본 프리페치 동작을 추가로 사용자 정의하세요.

자세한 내용은 [프리페치 가이드](/ko/guides/prefetch/)를 참조하세요.

### prefetch.prefetchAll

<p>

**타입:** `boolean`

</p>

`data-astro-prefetch` 속성이 없는 링크를 포함하여 모든 링크에 대해 프리페치를 활성화합니다.
`<ClientRouter />` 라우터를 사용할 때 이 값의 기본값은 `true`입니다. 그렇지 않은 경우 기본값은 `false`입니다.

```js
prefetch: {
  prefetchAll: true;
}
```

`true`로 설정하면 개별 링크에 `data-astro-prefetch="false"`를 설정하여 프리페치를 개별적으로 비활성화할 수 있습니다.

```html
<a href="/about" data-astro-prefetch="false">About</a>
```

### prefetch.defaultStrategy

<p>

**타입:** `'tap' | 'hover' | 'viewport' | 'load'`<br />
**기본값:** `'hover'`

</p>

`data-astro-prefetch` 속성이 없는 링크에 설정된 경우 사용할 기본 프리페치 전략입니다.

- `'tap'`: 링크를 클릭하기 직전에 미리 가져옵니다.
- `'hover'`: 링크 위로 마우스를 가져가거나 링크에 초점을 맞추면 미리 가져옵니다. (기본값)
- `'viewport'`: 링크가 뷰포트에 들어갈 때 미리 가져옵니다.
- `'load'`: 페이지가 로드된 후 페이지의 모든 링크를 미리 가져옵니다.

속성에 값을 설정하여 이 기본값을 무시하고 개별 링크에 대해 다른 전략을 선택할 수 있습니다.

```html
<a href="/about" data-astro-prefetch="viewport">About</a>
```

## 이미지 옵션

### image.endpoint

<p>

**타입:** `Object`<br />
**기본값:** `{route: '/_image', entrypoint: undefined}`<br />
<Since v="3.1.0" />
</p>

개발 및 SSR에서 이미지 최적화를 위해 사용할 엔드포인트를 설정합니다. `entrypoint` 속성을 `undefined`로 설정하여 기본 이미지 엔드포인트를 사용할 수 있습니다.

```js
{
  image: {
    // 예시: `/custom_endpoint`에서 사용자 지정 이미지 엔드포인트를 사용합니다.
    endpoint: {
		 	route: '/custom_endpoint',
		 	entrypoint: 'src/my_endpoint.ts',
		},
  },
}
```

### image.service

<p>

**타입:** `Object`<br />
**기본값:** `{entrypoint: 'astro/assets/services/sharp', config?: {}}`<br />

<Since v="2.1.0" />
</p>

Astro의 자산 지원에 사용되는 이미지 서비스를 설정합니다.

값은 이미지 서비스가 사용할 엔트리포인트가 있는 객체여야 하며 선택적으로 서비스에 전달할 구성 객체여야 합니다.

서비스 엔트리포인트는 포함된 서비스 중 하나이거나 타사 패키지일 수 있습니다.

```js
{
  image: {
    // 예: 사용자 정의 구성으로 Sharp 기반 이미지 서비스 활성화
    service: {
			 entrypoint: 'astro/assets/services/sharp',
			 config: {
				 limitInputPixels: false,
      },
		 },
  },
}
```

#### image.service.config.limitInputPixels

<p>

**타입:** `boolean`<br />
**기본값:** `true`<br />

<Since v="4.1.0" />
</p>

Sharp 이미지 서비스가 처리할 이미지 크기를 제한할지 여부입니다.

Sharp 이미지 서비스의 기본 이미지 크기 제한을 우회하고 큰 이미지를 처리하려면 `false`를 설정하세요.

### image.domains

<p>

**타입:** `Array<string>`<br />
**기본값:** `[]`<br />
<Since v="2.10.10" />
</p>

원격 이미지 최적화를 위해 허용되는 이미지 소스 도메인 목록을 정의합니다. 다른 원격 이미지는 Astro에서 최적화되지 않습니다.

이 옵션에는 개별 도메인 이름의 배열이 문자열로 필요합니다. 와일드카드는 허용되지 않습니다. 대신 [`image.remotePatterns`](#imageremotepatterns)를 사용하여 허용되는 소스 URL 패턴 목록을 정의하세요.

```js
// astro.config.mjs
{
  image: {
    // 예: 단일 도메인에서 원격 이미지 최적화 허용
    domains: ['astro.build'],
  },
}
```

### image.remotePatterns

<p>

**타입:** `Array<RemotePattern>`<br />
**기본값:** `[]`<br />

<Since v="2.10.10" />
</p>

원격 이미지 최적화를 위해 허용되는 이미지 소스 URL 패턴 목록을 정의합니다.

`remotePatterns`는 네 가지 속성으로 구성할 수 있습니다.

1. protocol
2. hostname
3. port
4. pathname

```js
{
  image: {
    // 예: aws s3 버킷의 모든 이미지 처리를 허용합니다.
    remotePatterns: [{
      protocol: 'https',
      hostname: '**.amazonaws.com',
    }],
  },
}
```

아래 설명과 같이 와일드카드를 사용하여 허용되는 `hostname` 및 `pathname` 값을 정의할 수 있습니다. 그렇지 않으면 제공된 정확한 값만 구성됩니다.
`hostname`:
- '**.' 로 시작하면 모든 하위 도메인 ('endsWith')을 허용합니다.
- '*.' 로 시작하면 한 수준의 하위 도메인만 허용합니다.

`pathname`:
- 모든 하위 경로 ('startsWith')를 허용하려면 '/\*\*' 로 끝납니다.
- 한 수준의 하위 경로만 허용하려면 '/\*' 로 끝납니다.

### image.responsiveStyles

<p>

**타입:** `boolean`<br />
**기본값:** `false`<br />
<Since v="5.10.0" />
</p>

반응형 이미지에 전역 스타일을 자동으로 추가할지 여부입니다. 이미지를 직접 스타일링하는 경우가 아니라면 이 옵션을 활성화해야 합니다.

이 옵션은 구성 또는 이미지 컴포넌트의 `layout` prop을 사용하여 `layout`이 `constrained`, `full-width`, `fixed`로 설정된 경우에만 사용할 수 있습니다.

자세한 내용은 [이미지 문서](/ko/guides/images/#반응형-이미지-스타일)를 참조하세요.

### image.layout

<p>

**타입:** `ImageLayout`<br />
**기본값:** `undefined`<br />
<Since v="5.10.0" />
</p>

반응형 이미지의 기본 레이아웃 타입입니다. 이미지 컴포넌트의 `layout` 속성으로 재정의할 수 있습니다.
- `constrained` - 이미지가 지정된 크기를 초과하지 않으면서 종횡비를 유지한 채로 컨테이너에 맞게 크기가 조정됩니다.
- `fixed` - 이미지가 원래 크기를 유지합니다.
- `full-width` - 이미지가 종횡비를 유지한 채로 컨테이너에 맞게 크기가 조정됩니다.

자세한 내용은 [`layout` 컴포넌트 속성](/ko/reference/modules/astro-assets/#layout)을 참조하세요.

### image.objectFit

<p>

**타입:** `ImageFit`<br />
**기본값:** `"cover"`<br />
<Since v="5.10.0" />
</p>

반응형 이미지의 [`object-fit` CSS 속성 값](https://developer.mozilla.org/ko/docs/Web/CSS/object-fit)입니다. 이미지 컴포넌트의 `fit` prop을 사용하여 재정의할 수 있습니다.
`layout`의 값을 먼저 설정해야 합니다.

자세한 내용은 [`fit` 컴포넌트 속성](/ko/reference/modules/astro-assets/#fit)을 참조하세요.

### image.objectPosition

<p>

**타입:** `string`<br />
**기본값:** `"center"`<br />
<Since v="5.10.0" />
</p>

반응형 이미지의 기본 [`object-position` CSS 속성 값](https://developer.mozilla.org/ko/docs/Web/CSS/object-position)입니다. 이미지 컴포넌트의 `position` prop을 사용하여 재정의할 수 있습니다.
`layout`의 값을 먼저 설정해야 합니다.

자세한 내용은 [`position` 컴포넌트 속성](/ko/reference/modules/astro-assets/#position)을 참조하세요.

### image.breakpoints

<p>

**타입:** `Array<number>`<br />
**기본값:** `[640, 750, 828, 1080, 1280, 1668, 2048, 2560] | [640, 750, 828, 960, 1080, 1280, 1668, 1920, 2048, 2560, 3200, 3840, 4480, 5120, 6016]`<br />
<Since v="5.10.0" />
</p>

반응형 이미지를 생성하는 데 사용되는 중단점입니다. `layout`의 값을 먼저 설정해야 합니다. 전체 목록은 일반적으로 사용되지 않으며, 소스 및 출력 크기에 따라 필터링됩니다. 사용되는 기본값은 로컬 또는 원격 이미지 서비스를 사용하는지에 따라 다릅니다. 원격 서비스의 경우 필요한 크기만 생성되므로 더 포괄적인 목록이 사용됩니다. 로컬 서비스의 경우 생성되는 이미지 수를 줄이기 위해 더 짧은 목록이 사용됩니다.

## Markdown 옵션

### markdown.shikiConfig

<p>

**타입:** `Partial<ShikiConfig>`
</p>

Shiki는 기본 구문 강조 도구입니다. `markdown.shikiConfig` 객체를 통해 모든 옵션을 구성할 수 있습니다:

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    shikiConfig: {
      // Shiki의 기본 제공 테마 중에서 선택하거나 나만의 테마를 추가하세요.
      // https://shiki.style/themes
      theme: 'dracula',
      // 또는 여러 테마를 제공하세요.
      // 라이트/다크 테마 사용은 아래를 참고하세요.
      themes: {
        light: 'github-light',
        dark: 'github-dark',
      },
      // 기본 색상을 비활성화합니다.
      // https://shiki.style/guide/dual-themes#without-default-color
      // (v4.12.0에서 추가됨)
      defaultColor: false,
      // 사용자 정의 언어를 추가합니다.
      // 참고: Shiki에는 .astro를 포함하여 수많은 언어가 기본적으로 제공됩니다!
      // https://shiki.style/languages
      langs: [],
      // 언어에 대한 사용자 지정 별칭을 추가합니다.
      // 별칭을 Shiki 언어 ID에 매핑: https://shiki.style/languages#bundled-languages
      // https://shiki.style/guide/load-lang#custom-language-aliases
      langAlias: {
        cjs: "javascript"
      },
      // 가로 스크롤을 방지하려면 word wrap을 활성화하세요.
      wrap: true,
      // 사용자 정의 transformers 추가: https://shiki.style/guide/transformers
      // 일반 transformers 찾기: https://shiki.style/packages/transformers
      transformers: [],
    },
  },
});
```

사용법과 예시는 [코드 구문 강조 표시 가이드](/ko/guides/syntax-highlighting/)를 참조하세요.

### markdown.syntaxHighlight

<p>

**타입:** `SyntaxHighlightConfig | SyntaxHighlightConfigType | false`<br />
**기본값:** `{ type: 'shiki', excludeLangs: ['math'] }`
</p>

Markdown 코드 블록 (\`\`\`)에 사용할 구문 강조기를 선택합니다. 이는 Astro가 Markdown 코드 블록에 적용할 CSS 클래스를 결정합니다.

- `shiki` - [Shiki](https://shiki.style) 구문 강조기를 사용합니다. (기본적으로 `github-dark` 테마가 구성됩니다.)
- `prism` - [Prism](https://prismjs.com/) 구문 강조기를 사용하고, [나만의 Prism 스타일시트를 제공합니다.](/ko/guides/syntax-highlighting/#prism-스타일시트-추가)
- `false` - 구문 강조를 적용하지 않습니다.
```js
{
  markdown: {
    // 예: Markdown에서 구문 강조를 위해 Prism을 사용하도록 전환
    syntaxHighlight: 'prism',
  }
}
```

구문 강조에 대한 더 많은 제어를 위해, 아래 나열된 속성을 사용하여 구성 객체를 지정할 수 있습니다.

#### markdown.syntaxHighlight.type

<p>

**타입:** `'shiki' | 'prism'`<br />
**기본값:** `'shiki'`<br />
<Since v="5.5.0" />
</p>

Markdown 코드 블록에 적용할 기본 CSS 클래스입니다. (다른 구문 강조 구성이 필요하지 않은 경우, `markdown.syntaxHighlight`를 `shiki`, `prism` 또는 `false`로 직접 설정할 수 있습니다.)

#### markdown.syntaxHighlight.excludeLangs

<p>

**타입:** `Array<string>`<br />
**기본값:** `['math']`<br />
<Since v="5.5.0" />
</p>

`markdown.syntaxHighlight.type`에 지정된 기본 구문 강조에서 제외할 언어의 배열입니다.
Mermaid.js 및 D2와 같이 Markdown 코드 블록에서 다이어그램을 생성하는 도구를 사용할 때 유용할 수 있습니다.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    syntaxHighlight: {
      type: 'shiki',
      excludeLangs: ['mermaid', 'math'],
    },
  },
});
```

### markdown.remarkPlugins

<p>

**타입:** `RemarkPlugins`

</p>

[remark 플러그인](https://github.com/remarkjs/remark)을 전달하여 Markdown 빌드 방법을 맞춤설정하세요. 플러그인 기능을 가져와 적용하거나 (권장) 플러그인 이름을 문자열로 전달할 수 있습니다.

```js
import remarkToc from 'remark-toc';
{
  markdown: {
    remarkPlugins: [ [remarkToc, { heading: "contents"} ] ]
  }
}
```

### markdown.rehypePlugins

<p>

**타입:** `RehypePlugins`

</p>

[rehype 플러그인](https://github.com/remarkjs/remark-rehype)을 전달하여 Markdown의 출력 HTML이 처리되는 방식을 맞춤설정하세요. 플러그인 기능을 가져와 적용하거나 (권장) 플러그인 이름을 문자열로 전달할 수 있습니다.

```js
import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';
{
  markdown: {
    rehypePlugins: [rehypeAccessibleEmojis];
  }
}
```

### markdown.gfm

<p>

**타입:** `boolean`<br />
**기본값:** `true`<br />

<Since v="2.0.0" />
</p>

Astro는 기본적으로 [GitHub 기반 Markdown](https://github.com/remarkjs/remark-gfm)을 사용합니다. 이를 비활성화하려면 `gfm` 플래그를 `false`로 설정하세요.

```js
{
  markdown: {
    gfm: false,
  }
}
```

### markdown.smartypants

<p>

**타입:** `boolean`<br />
**기본값:** `true`<br />

<Since v="2.0.0" />
</p>

Astro는 기본적으로 [SmartyPants 포매터](https://daringfireball.net/projects/smartypants/)를 사용합니다. 이를 비활성화하려면 `smartypants` 플래그를 `false`로 설정하세요.

```js
{
  markdown: {
    smartypants: false,
  }
}
```

### markdown.remarkRehype

<p>

**타입:** `RemarkRehype`

</p>

옵션을 [remark-rehype](https://github.com/remarkjs/remark-rehype#api)에 전달하세요.

```js
{
  markdown: {
    // 예: 각주 텍스트를 다른 언어로 번역합니다. 기본 영어 값은 다음과 같습니다.
    remarkRehype: { footnoteLabel: "Footnotes", footnoteBackLabel: "Back to reference 1"},
  },
};
```

## i18n

<p>

**타입:** `object`<br />

<Since v="3.5.0" />
</p>

i18n 라우팅을 구성하고 일부 맞춤 옵션을 지정할 수 있습니다.

[Astro의 국제화](/ko/guides/internationalization/)에 대한 자세한 내용은 가이드를 참조하세요.

### i18n.locales

<p>

**타입:** `Locales`<br />
<Since v="3.5.0" />
</p>

웹사이트가 지원하는 모든 로케일 목록입니다. 이는 필수 필드입니다.

언어는 개별 코드(예: `['en', 'es', 'pt-br']`)로 나열하거나 공유된 `path` 코드에 매핑(예: `{ path: "english", codes: ["en", "en-US"]}`)할 수 있습니다. 이러한 코드는 배포된 사이트의 URL 구조를 결정하는 데 사용됩니다.

특정 언어 코드 형식이나 구문이 강제되지는 않지만, 콘텐츠 파일이 포함된 프로젝트 폴더는 목록의 `locales` 항목과 정확히 일치해야 합니다. 사용자 정의 URL 경로 접두사를 가리키는 여러 `codes`의 경우, 구성된 `path`와 동일한 이름의 폴더에 콘텐츠 파일을 저장하세요.

### i18n.defaultLocale

<p>

**타입:** `string`<br />
<Since v="3.5.0" />
</p>

웹사이트/애플리케이션의 기본 로케일로, 지정된 `locales` 중 하나입니다. 이는 필수 필드입니다.

특정 언어 형식이나 구문이 적용되지는 않지만 호환성을 극대화하려면 필요에 따라 소문자와 하이픈 (예: "es", "pt-br")을 사용하는 것이 좋습니다.

### i18n.fallback

<p>

**타입:** `Record<string, string>`<br />

<Since v="3.5.0" />
</p>

존재하지 않는 페이지로 이동할 때의 대체 전략 (예: 번역된 페이지가 생성되지 않음)

이 객체를 사용하여 지원하는 각 언어에 대한 대체 `locale` 경로를 선언하세요. 대체가 지정되지 않으면 사용할 수 없는 페이지는 404를 반환합니다.

##### 예

다음 예시는 `/pt-br/`에서 사용할 수 없는 페이지를 `es` 버전으로 리디렉션하고, `/fr/`에서 사용할 수 없는 페이지를 `en` 버전으로 리디렉션하도록 콘텐츠 대체 전략을 구성합니다. 사용할 수 없는 `/es/` 페이지는 404를 반환합니다.

```js
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr', 'pt-br', 'es'],
    fallback: {
      pt: 'es',
      fr: 'en',
    },
  },
});
```

### i18n.routing

<p>

**타입:** `object | "manual"`<br />
**기본값:** `object`<br />
<Since v="3.7.0" />
</p>

사이트 URL을 결정하기 위한 라우팅 전략을 제어합니다. 기본 언어에 대한 폴더/URL 경로 구성을 기반으로 이를 설정합니다.

```js
export default defineConfig({
	i18n: {
		defaultLocale: "en",
		locales: ["en", "fr"],
		routing: {
			prefixDefaultLocale: false,
			redirectToDefaultLocale: true,
			fallbackType: "redirect",
		}
	}
})
```

4.6.0부터 이 옵션을 `manual`로 설정할 수도 있습니다. 이 라우팅 전략이 활성화되면 Astro는 i18n 미들웨어를 **비활성화**하고 다른 `routing` 옵션 (예: `prefixDefaultLocale`)은 구성할 수 없습니다. 자체 라우팅 로직을 작성하거나 자체 로직과 함께 Astro의 i18n 미들웨어를 직접 실행해야 합니다.

```js
export default defineConfig({
	i18n: {
		defaultLocale: "en",
		locales: ["en", "fr"],
		routing: "manual"
	}
})
```

#### i18n.routing.prefixDefaultLocale

<p>

**타입:** `boolean`<br />
**기본값:** `false`<br />

<Since v="3.7.0" />
</p>

`false`인 경우 기본이 아닌 언어에만 언어 접두사가 표시됩니다.
`defaultLocale`은 언어 접두사를 표시하지 않으며, 콘텐츠 파일은 현지화된 폴더에 존재하지 않습니다.
URL은 기본이 아닌 모든 언어의 경우 `example.com/[locale]/content/` 형식이지만 기본 언어의 경우 `example.com/content/` 형식입니다.

`true`인 경우 모든 URL에 언어 접두사가 표시됩니다.
URL은 기본 언어를 포함하여 모든 경로에 대해 `example.com/[locale]/content/` 형식입니다.
현지화된 폴더는 기본값을 포함하여 모든 언어에 사용됩니다.

```js
export default defineConfig({
	i18n: {
		defaultLocale: "en",
		locales: ["en", "fr", "pt-br", "es"],
		routing: {
			prefixDefaultLocale: true,
		}
	}
})
```

#### i18n.routing.redirectToDefaultLocale

<p>

**타입:** `boolean`<br />
**기본값:** `true`<br />

<Since v="4.2.0" />
</p>

`prefixDefaultLocale: true`가 설정된 경우 `src/pages/index.astro`에 의해 생성된 홈 URL (`/`)이 `/[defaultLocale]`로 리디렉션되는지 여부를 구성합니다.

사이트 루트에서 자동 리디렉션을 비활성화하려면 `redirectToDefaultLocale: false`를 설정하세요.

```js
// astro.config.mjs
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
    routing: {
      prefixDefaultLocale: true,
      redirectToDefaultLocale: false,
    },
  },
});
```

#### i18n.routing.fallbackType

<p>

**타입:** `"redirect" | "rewrite"`<br />
**기본값:** `"redirect"`<br />
<Since v="4.15.0" />
</p>

누락된 페이지 경로에 대해 404 페이지를 표시하지 않도록 [`i18n.fallback`](#i18nfallback)을 구성한 경우 이 옵션은 대체 페이지로 [리디렉션](/ko/guides/routing/#리디렉션)할 것인지 아니면 대체 페이지의 콘텐츠를 그대로 [리라이트](/ko/guides/routing/#url-재작성-rewrites)할 것인지 제어합니다.

기본적으로 Astro의 i18n 라우팅은 대체 구성에 따라 방문자를 새 목적지로 리디렉션하는 페이지를 생성합니다. 브라우저가 새로고침되고 URL 표시줄에 목적지 주소가 표시됩니다.

`i18n.routing.fallback: "rewrite"`이 구성되면 Astro는 요청된 원본 URL에 대체 페이지의 콘텐츠를 렌더링하는 페이지를 생성합니다.

다음 구성의 경우, `src/pages/en/about.astro` 파일은 있지만 `src/pages/fr/about.astro`가 없는 경우 `astro build` 명령은 `dist/en/about.html` 페이지와 동일한 내용의 `dist/fr/about.html`을 생성합니다.
사이트 방문자는 `https://example.com/fr/about/`에서 영문 버전의 페이지를 볼 수 있으며 리디렉션되지 않습니다.

```js
//astro.config.mjs
export default defineConfig({
	 i18n: {
    defaultLocale: "en",
    locales: ["en", "fr"],
    routing: {
    	prefixDefaultLocale: false,
    	fallbackType: "rewrite",
    },
    fallback: {
    	fr: "en",
    }
  },
})
```

### i18n.domains

<p>

**타입:** `Record<string, string>`<br />
**기본값:** `{}`<br />
<Since v="4.3.0" />
</p>

지원되는 하나 이상의 언어에 대한 URL 패턴이 사용자 정의 도메인 (또는 하위 도메인)을 사용하도록 구성합니다.

로케일이 도메인에 매핑되면 `/[locale]/` 경로 접두사가 사용되지 않습니다.
하지만 구성된 `defaultLocale`을 포함하는 `src/pages/`의 현지화된 폴더는 여전히 필요합니다.

구성되지 않은 다른 로케일은 기본적으로 `prefixDefaultLocale` 전략에 따라 현지화된 경로 기반 URL을 사용합니다. (예: `https://example.com/[locale]/blog`)

```js
//astro.config.mjs
export default defineConfig({
	 site: "https://example.com",
	 output: "server", // 사전 렌더링된 페이지가 없다면 필수
	 adapter: node({
	   mode: 'standalone',
	 }),
	 i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
    prefixDefaultLocale: false,
    domains: {
      fr: "https://fr.example.com",
      es: "https://example.es"
    }
  },
})
```

빌드된 페이지 라우트와 `astro:i18n`의 도우미 함수인 [`getAbsoluteLocaleUrl()`](/ko/reference/modules/astro-i18n/#getabsolutelocaleurl) 및 [`getAbsoluteLocaleUrlList()`](/ko/reference/modules/astro-i18n/#getabsolutelocaleurllist)에 의해 반환된 URL은 모두 `i18n.domains`에 설정된 옵션을 사용합니다.

이 기능의 제한 사항을 포함한 자세한 내용은 [국제화 가이드](/ko/guides/internationalization/#domains)를 참조하세요.

## env

<p>

**타입:** `object`<br />
**기본값:** `{}`<br />
<Since v="5.0.0" />
</p>

타입 안전 환경 변수를 위한 구성 옵션입니다.

Astro의 [환경 변수](/ko/guides/environment-variables/)에 대한 자세한 정보는 가이드를 참조하세요.

### env.schema

<p>

**타입:** `EnvSchema`<br />
**기본값:** `{}`<br />
<Since v="5.0.0" />
</p>

`envField`를 사용하여 환경 변수의 데이터 타입과 속성을 정의하는 객체입니다: `context`(클라이언트 또는 서버), `access`(공개 또는 비밀), 사용할 `default` 값, 그리고 이 환경 변수가 `optional`인지 여부(기본값은 `false`).

```js
// astro.config.mjs
import { defineConfig, envField } from "astro/config"

export default defineConfig({
  env: {
    schema: {
      API_URL: envField.string({ context: "client", access: "public", optional: true }),
      PORT: envField.number({ context: "server", access: "public", default: 4321 }),
      API_SECRET: envField.string({ context: "server", access: "secret" }),
    }
  }
})
```

`envField`는 문자열, 숫자, 열거형, 불리언의 네 가지 데이터 타입을 지원합니다. `context`와 `access`는 모든 데이터 타입에 필요한 속성입니다. 다음은 각 데이터 타입에 사용할 수 있는 전체 속성 목록입니다:

```js
import { envField } from "astro/config"

envField.string({
   // context & access
   optional: true,
   default: "foo",
   max: 20,
   min: 1,
   length: 13,
   url: true,
   includes: "oo",
   startsWith: "f",
   endsWith: "o",
})
envField.number({
   // context & access
   optional: true,
   default: 15,
   gt: 2,
   min: 1,
   lt: 3,
   max: 4,
   int: true,
})
envField.boolean({
   // context & access
   optional: true,
   default: true,
})
envField.enum({
   // context & access
   values: ['foo', 'bar', 'baz'], // 필수
   optional: true,
   default: 'baz',
})
```

### env.validateSecrets

<p>

**타입:** `boolean`<br />
**기본값:** `false`<br />
<Since v="5.0.0" />
</p>

개발 서버를 시작하거나 빌드를 실행할 때 서버에서 비밀의 유효성을 검사할지 여부입니다.

기본적으로 개발 서버나 빌드를 시작할 때 서버에서는 공개 변수만 검증되고, 비공개 변수는 런타임에만 검증됩니다. 이 옵션이 활성화되면 개발 서버나 빌드 시작 시 비공개 변수도 함께 검증됩니다. 이는 일부 CI (지속적 통합) 파이프라인에서 배포하기 전에 모든 비밀이 올바르게 설정되었는지 확인하는 데 유용합니다.

```js
// astro.config.mjs
import { defineConfig, envField } from "astro/config"

export default defineConfig({
  env: {
    schema: {
      // ...
    },
    validateSecrets: true
  }
})
```
